Campaign Creation API Endpoints

#1

Campaign creation endpoints

Open API endpoints in Infosec IQ allow you to automate more of your SAT program. New endpoints have been introduced that allow you to create campaigns without using the app interface, saving significant time when creating multiple campaigns simultaneously. Additional endpoint details, recommended workflows and examples are below, full open API documentation can be found here.

Campaign creation endpoints can be especially useful as an MSP managing multiple accounts, or a standard account user creating multiple campaigns for different departments or groups. The key to this automation is finding what configuration works for your organization or customers, and then writing a script to let the APIs do the work for you.

Applicable endpoints

Asset endpoints

Asset endpoints provide IDs and specifics needed when creating campaigns via API.

AwareEd specific
  1. Courses: /courses provides a list of courses available to your account, including Infosec created (system) courses, shared courses and personal courses.
    • /courses/{id} provides more information about a specific course, including name, subtitle, description, duration, ownership, and a list of specific assets within the course.
  2. Language: /languages provides a list of the languages available to set your AwareEd campaign default to. As within the UI, this will be overridden by your learners’ personalized settings if applicable.
PhishSim specific
  1. Templates: /templates provides a list of PhishSim templates available to your account, including system, contributed, personal and shared templates.
  2. Batteries: /batteries provides a list of PhishSim batteries available to your account, including system and personal batteries.
  3. Categories: /categories provides a list of PhishSim email template categories.
Both
  1. Groups: /learner-groups provides a list of groups from your account, including static and dynamic groups.
    • /learner-groups/{id}/learners provides a list of each learner in the specified group.
  2. Learners: /learners provides a list of individual learners from your account for more targeted phishing and training campaigns.
  3. Notifications: /notifications provides a list of all notifications available to your account, including system, shared, and personal notifications. This list will include AwareEd, PhishSim and PhishHunter notifications, but only AwareEd and PhishSim notifications will be needed for creating campaigns.
  4. Branding: /branding provides a list of brand options available in your account.

Campaign endpoints

Campaign endpoints allow you to create campaigns via the API. Endpoints match in app functionality with a few exceptions as noted below. Endpoints can only save and schedule campaigns and cannot be used to create drafts.

  1. AwareEd campaigns: /campaigns/awareed
    • Not supported: New hire campaigns and notifications to recipients other than learners and managers.
  2. PhishSim campaigns: /campaigns/phishsim
    • Not supported: defined delivery times and pattern tracking for BEC emails.
  3. Previous campaign details: /campaigns/details/{id} allows you to pull the details of a previous campaign in the same format as the above endpoints, allowing you to make small adjustments, such as start date, and then easily recreate the campaign. This is similar to the “clone” functionality that exists in the IQ app.
    • Use /campaigns to obtain the list of campaign IDs for the above.

Recommended workflows

The following workflows are recommended for using the above endpoints, but not required.

Global Admin accounts

Global admin accounts have additional features to assist in automation for campaign creation across sub accounts.

API Keys

This page allows you to see and export a list of all sub accounts and their associated API keys. You can also use this page to create or delete keys per sub account. Note: sub accounts without API keys will appear on this list, and sub accounts with multiple API keys (up to 5) will appear multiple times.

GA Workflow

  1. Create API keys for each sub account using “API Keys” and export this list.
  2. Confirm preferred settings and content for your campaign by sending yourself a test campaign. This can be done via API or through the UI.
  3. Use asset endpoints listed above to retrieve applicable IDs.
  4. Format campaign creation endpoint(s) with above and preferred settings.
  5. Write a script that cycles through the above API keys and campaign format.

Standard accounts

Standard (non GA) accounts can use the same workflow as above, but can create API keys on Infosec IQ NA or Infosec IQ EU.

  1. Confirm preferred settings and content for your campaign by sending yourself a test campaign. This can be done via API or through the app.
  2. Use asset endpoints listed above to retrieve applicable IDs.
  3. Format campaign creation endpoint(s) with above and preferred settings.
  4. Create a campaign using the above campaign format.

Example campaigns

Note: no real ID’s are used in the below campaign examples.

AwareEd examples

To create a set of AwareEd campaigns via API, first find or create a course that fits your organization/customers needs and then build the campaign around this. You can customize campaigns by creating the campaign in app, and pulling the details of that campaign to recreate it, or by using the asset endpoints to pull all options and configure the campaign.

Notifications are an area to pay special attention to, you will need to set the ID for email template, the recipient (learner or manager), and the interval and repeat cadence (for start and finish notifications). There are some exceptions that cannot be completed via API (noted above) but this endpoint will allow you to save time and ensure consistency across your program!

One month, single run, AwareEd campaign to all learners

{
"name": "Work Bytes Introduction",
"course_id": "ExampleID",
"is_test": false,
"branding_id": "ExampleID",
"language_id": "ExampleID",
"autoplay": true,
"enable_completion_cert": true,
"require_assessment_retake": true,
"lock_learners_out": false,
"learner_auth_enabled": false,
"reset_progress": false,
"schedule_interval_units": "number_of_days",
"number_of_days": 30,
"number_of_repeats": 0,
"start_date": "2024-01-01",
"notifications": [
{
"template_id": "ExampleID",
"recipient": "learner”
},
{
"template_id": "ExampleID",
"recipient": "learner",
"interval":3,
"repeat": false
},
{
"template_id": "ExampleID",
"recipient": "learner",
"interval":7,
"repeat": true
},
{
"template_id": "ExampleID",
"recipient": "learner”
}
],
"all_learners": true
}

Quarterly AwareEd campaigns to a single learner and single group with the “Core Concepts: MFA Fatigue” course with manager notifications.

{
"name": "Core Concepts: MFA Fatigue - Department Training",
"course_id": "ExampleID",
"is_test": false,
"branding_id": "ExampleID",
"language_id": "ExampleID",
"autoplay": true,
"enable_completion_cert": true,
"require_assessment_retake": true,
"lock_learners_out": false,
"learner_auth_enabled": false,
"reset_progress": false,
"schedule_interval_units": "quarter",
"start_date": "2024-01-01",
"notifications": [
{
"template_id": "ExampleID",
"recipient": "learner”
},
{
"template_id": "ExampleID",
"recipient": "learner",
"interval":3,
"repeat": false
},
{
"template_id": "ExampleID",
"recipient": "learner",
"interval":7,
"repeat": true
},
{
"template_id": "ExampleID",
"recipient": "manager",
"interval":7,
"repeat": true
},
{
"template_id": "ExampleID",
"recipient": "learner”
}
],
"all_learners": false,
"learner_group_ids": [“ExampleID”],
"learner_ids": [“ExampleID”]
}

PhishSim examples

Creation of a PhishSim campaign follows very similar steps to the AwareEd creation process. First, preview the content you wish to use, or look at the general category of content to find what email templates will be the best practice for your organization. Then, decide the cadence for sending. PhishSim campaigns allow you to select a large number of email templates and specify that learners only receive a small set of these (template_send_count). These campaigns can also be repeated monthly/quarterly/etc for even more automation, such as the Catch of the Week example below.

PhishSim campaign with monthly runs, sending two emails to all learners per month, from the Catch of the Week email template category.

{
"name": "Monthly Catch of the Week Campaign",
"is_test": false,
"categories": ["ExampleID"],
"send_all_templates": false,
"template_send_count": 2,
"track_replies": false,
"branding_id": "ExampleID",
"schedule_interval_units": "month",
"start_date": "2024-01-01",
"phished_notification_id": "ExampleID",
"add_phished_learners_to_group_id": "ExampleID",
"all_learners": true
}

Baseline PhishSim campaign to a specific department and specific learner running once over 14 days and not sending a follow up notification.

{
"name": "Baseline Blind Campaign - Finance Department",
"is_test": false,
"batteries": ["ExampleID"],
"send_all_templates": true,
"track_replies": false,
"branding_id": "ExampleID",
"schedule_interval_units": "number_of_days",
"number_of_days": 14,
"number_of_repeats": 0,
"start_date": "2024-01-01",
"all_learners": false,
"learner_group_ids": ["ExampleID"],
"learner_ids": ["ExampleID"]
}

Additional Documentation

Click here for the complete Infosec IQ Open API documentation.

Infosec IQ API Support

The Infosec IQ Open API is provided with limited support. We can provide guidance about the functionality of our API endpoints but we are unable to assist with writing code or creating integrations with other software.